CMakeSettings.json looks like a user file generated by Visual Studio, similar to Qt Creator's CMakeLists.txt.user. It should not be part the repository (it would have its place in a .gitignore though).

Having longer instructions for Visual Studio is fine, but adding a subsection would be better, so other users can skip it.

CMakeSettings.json definitely belongs into version control. It contains similar information to what a .vcxproj might contain, in particular build variables.

It seems Visual Studio is in the process of integrating CMake Presets:
https://docs.microsoft.com/en-us/cpp/build/cmake-presets-vs?view=msvc-160
https://devblogs.microsoft.com/cppblog/cmake-presets-integration-in-visual-studio-and-visual-studio-code/
I haven't had time to play around with those but that would be an alternative. Still, CMakeSettings.json works even for those who don't have the very latest VS version, so I'd call that the pragmatic solution.

Sure, we can split the doc into subsections if you prefer. I was just going for the least invasive change. What do you want the sections to be? Just Windows/Linux or do you want to split Windows into VS/non-VS?

CMakeSettings.json is never modifier if a user tweak their configuration? That would cause issues.

Assuming it belongs in version control, the next questions is: Why would I want presets and why would I want your presets?

Sure, we can split the doc into subsections if you prefer. I was just going for the least invasive change. What do you want the sections to be? Just Windows/Linux or do you want to split Windows into VS/non-VS?

Simply add something like ### Building with Microsoft Visual C++ before the part you added (it was the beginning of the paragraph you replaced).

CMakeSettings.json is never modifier if a user tweak their configuration? That would cause issues.

Assuming it belongs in version control, the next questions is: Why would I want presets and why would I want your presets?

You don't want my presets but you want reasonable presets. The presets are what gets VS users started the most quickly and without needing to install any dependencies.

If a user tweaks their configuration obviously that's going to change the CMakeSettings.json, just like it would be the case with a VS project file or the CMake Presets. After all, you might want to check in such changes.

Simply add something like ### Building with Microsoft Visual C++ before the part you added (it was the beginning of the paragraph you replaced).

Ok, I'll push that change a bit later.

I added an extra heading as discussed.